\documentclass[12pt,a4paper]{report}
\usepackage[top=2.5cm, bottom=2.5cm, left=2.5cm, right=2.5cm]{geometry}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage[round]{natbib}
\usepackage{graphicx}
\usepackage{tabularx}
\usepackage{algorithm}
\usepackage{algpseudocode}
\usepackage{listings}
\usepackage[usenames,dvipsnames,svgnames]{xcolor}
\usepackage{url}
\newcommand{\vect}[1]{\boldsymbol{#1}}
\usepackage{hyperref}
\hypersetup{
pdfnewwindow=true,      % links in new window
colorlinks=true,        % false: boxed links; true: colored links
linkcolor=Blue,         % color of internal links
citecolor=Blue,         % color of links to bibliography
filecolor=Blue,         % color of file links
urlcolor=Blue           % color of external links
}

\begin{document}

\begin{center}
  \huge
  {
   \vspace*{1.0cm}
   GPUGA: \\
   Graphics Processing Units Genetic Algorithm \\
   \vspace*{1.0cm}
   Reference Manual\\
   \vspace*{1.0cm}
   Version 1.0 \\
   \vspace*{1.0cm}
   (Nov 08, 2019)\\
  \vspace*{2.0cm}
  }
  \large
  {
  Author: \\
  Zheyong Fan (Bohai University and Aalto University)\\
  }
  \vspace*{1.0cm}
\end{center}

\tableofcontents

\chapter{Introduction\label{chapter:introduction}}

\section{What is GPUGA?}

\verb"GPUGA" stands for Graphics Processing Units Genetic Algorithm. It is a highly efficient empirical potential fitting code using the genetic algorithm (GA) implemented on graphics processing units (GPU). The implementation language is CUDA C++. \textbf{Fitting one empirical potential only takes about one minute using GPUGA. }

\verb"GPUGA" was developed for \cite{fan2019arxiv}. If you use \verb"GPUGA" in your published work, we kindly ask you to cite this paper.

This is version 1.0, and it can only be used to fit the minimal Tersoff potential as proposed in \cite{fan2019arxiv}. We aim to implement more empirical potentials for version 2.0.

All the potentials considered in \verb"GPUGA" will be implemented in the \verb"GPUMD" package, which can be found here:

\url{https://github.com/brucefan1983/GPUMD}

\section{Feedback}

You can email Dr. Zheyong Fan if you find errors in the manual or bugs in the source code, or have any suggestions/questions about the manual and code. The following email address can be used:
\begin{itemize}
\item brucenju(at)gmail.com
\end{itemize}

\section{Acknowledgments}
We acknowledge the computational resources provided by Aalto Science-IT project and Finland's IT Center for Science (CSC).

\chapter{Theoretical formalisms\label{section:theory}}

See \cite{fan2019arxiv}. 

\chapter{Using GPUGA \label{section:usage}}

The code has only been tested in linux operating systems and we assume that the user is using a linux operating system to compile and run this code.

\section{Compile the code and run the examples}

\subsection{Compiling}

After downloading and unpacking \verb"GPUGA", one can see four folders:  \verb"src",  \verb"examples",  \verb"tools", and \verb"doc". The folder \verb"src" contains all the source files. The folder \verb"examples" contains all the examples. The folder \verb"tools" contains a Matlab script for plotting Fig. 3 in \cite{fan2019arxiv}. The folder \verb"doc" contains the pdf file you are reading and the source files generating it.

To compile the code, go to the \verb"src" folder and type
\begin{verbatim}
    make
\end{verbatim}
in the command line. This will produce an executable called \verb"gpuga" in the \verb"src" folder. The second line of \verb"makefile" reads
\begin{verbatim}
    CFLAGS = -std=c++11 -O3 -arch=sm_50 --use_fast_math
\end{verbatim}
Change \verb"50" to the appropriate ``compute capability'' of your GPU. The minimum compute capability supported by \verb"GPUGA" is 3.5.

\subsection{Running}

Go to the directory where you can see the \verb"src" folder and type
\begin{verbatim}
    src/gpuga < examples/input.txt
\end{verbatim}
This will run the prepared example. To run your own calculations, just replace the folder name (including absolute or relative path) as specified in \verb"examples/input.txt" to your own working directory. Then you need to prepare some input files in the working directory.

\section{Units used in the input and output files}

In all the input and output files, we use the following units:
\begin{itemize}
\item length (box vectors and positions): \AA
\item energy: eV
\item virial (virial is the product of position and force): eV
\item force: eV/\AA
\end{itemize}

\section{Input files for GPUGA}

To run one simulation with \verb"GPUGA", you need to prepare three input files in your chosen working directory: \verb"ga.in", \verb"potential.in", and \verb"train.in". We describe them below.

\subsection{The ga.in input file}

This file contains the controlling parameters defining the GA evolution. In this input file, blank lines and lines starting with \verb"#" are ignored. Each non-empty line starts with a keyword followed by one parameter.  The valid keywords and their parameters are listed below.
\begin{enumerate}
\item  \verb"maximum_generation"\\
This keyword needs one parameter, which is the maximum number of generations in the GA evolution. It should be a positive integer. The default value is 1000.
\item  \verb"population_size" \\
This keyword needs one parameter, which is the population size (number of individuals in one generation). It should be no less than 20 and should be a multiple of 10. The default value is 200.
\item  \verb"parent_number"\\
This keyword needs one parameter, which is the number of parents in one generation. It can be no less than 10 and should be a multiple of 10. The default value is 100.
\item  \verb"mutation_rate"\\
This keyword needs one parameter, which is the initial mutation rate in the GA evolution. It should be in $[0,1]$. The default value is 0.2. The mutation rate will linearly decrease and reach 0 up to step \verb"maximum_generation".
\end{enumerate}

\subsection{The potential.in input file}

This file contains information about the potential to be fitted. It has a fixed format. For example, the file \verb"examples/si_diamond/potential.in" reads:
\begin{verbatim}
potential_type 1
cutoff         3.0
weight_force   0.05
weight_energy  0.15
weight_virial  0.8
D0             2.9 3.3
alpha          1.3 1.5
r0             2.2 2.4
S              2 2
n              0.5 0.8
beta           0 0.4
h              -0.8 -0.6
R1             2.8 2.8
R2             3.2 3.2
\end{verbatim}
At each line, there is one character string and one or two numbers. To do new experiments, just keep the strings unchanged and modify the numbers. Here are some explanations:
\begin{itemize}
\item Line 1: The type of the potential to be fitted, which can only be 1  (means the minimal Tersoff potential \cite{fan2019arxiv}) in this version.
\item Line 2: The cutoff distance (in units of \AA) used for building the neighbor list for each configuration (see below), which should be a positive number.
\item Lines 3-5: The weighting factors (dimensionless) for force, energy, and virial. They should be non-negative numbers. It is good to make their sum to be 1, although the code does not complain if this is not the case.
\item Lines 6-14: The lower (the first number in each line) and upper (the second number in each line) bounds of the potential parameters for the minimal Tersoff potential. The order of the parameters are the same as those in Table II of \cite{fan2019arxiv}, where one can find the units of the parameters. 
\end{itemize}

\subsection{The train.in input file}

This file contains all the training data, possibly from DFT calculations. The format is fixed:
\begin{verbatim}
Nc Nc_force
N_1
N_2
...
N_Nc
Data for force configuration 1
Data for force configuration 2
...
Data for force configuration Nc_force
Data for energy/virial configuration 1
Data for energy/virial configuration 2
...
Data for energy/virial configuration Nc - Nc_force
\end{verbatim}
Here, 
\begin{itemize}
\item \verb"Nc" is the total number of configurations.
\item \verb"Nc_force" is the total number of force configurations. \verb"Nc - Nc_force" is the number of energy/virial configurations.
\item \verb"N_i" is the number of atoms in configuration \verb"i". All the force configurations should come before all the energy/virial configurations.
\item Data for one force configuration occupy \verb"N_i + 1" lines. The first line should have nine numbers defining the cell vectors ($\vect{a}$, $\vect{b}$, $\vect{c}$):
\begin{verbatim}
    ax ay az bx by bz cx cy cz
\end{verbatim} 
These numbers are in units of \AA. In the remaining \verb"N_i" lines, each line contains 7 numbers, corresponding to the atom type (not used in this version and can be set to 0), position components (in units of \AA), and force components (in units of eV/\AA):
\begin{verbatim}
    type x y z fx fy fz
\end{verbatim} 
\item Data for one energy/virial configuration occupy \verb"N_i + 2" lines. The first line should have 7 numbers. The first one is the total energy (in units of eV) of the current configuration. The remaining 6 numbers are the $xx$, $yy$, $zz$, $xy$, $yz$, and $zx$ components of the virial tensor (in units of eV) of the current configuration. The second line gives the cell vectors, similar to the first line for the force configurations. The remaining \verb"N_i" lines are similar to those in the force configurations, but each line only has 4 numbers, which are the atom type and position components.
\end{itemize}

\section{Output files of GPUGA}

For each simulation, four output files will be generated in the working directory: \verb"ga.out", \verb"force.out", \verb"energy.out", and \verb"virial.out". Repeating a simulation will remove the existing results and only keep the new results. A Matlab script \verb"plot_results.m" can be used to plot a figure similar to Fig. 2 in \cite{fan2019arxiv}.

\subsection{The ga.out file}

This file will contain \verb"maximum_generation" lines (or less if the simulation is terminated before completion) and 11 columns. Each line contains the following items
\begin{verbatim}
step best_fitness D0 alpha r0 S n beta h R1 R2
\end{verbatim}
Here, \verb"step" is the step in the GA evolution, starting with 0, \verb"best_fitness" is the fitness function (the smaller, the better) for the elite (the best solution) in each generation, and the remaining 9 numbers are the potential parameters (in the same order as in \verb"potential.in") for the elite in each generation.

To find the best solution for one simulation, just check the last line.

\subsection{The force.out file}

There are 6 columns. The first three columns are the $x$, $y$, and $z$ force components (in units of eV/\AA) in the force configurations calculated from the best solution. The last three columns are the corresponding forces (in units of eV/\AA) from \verb"train.in". The first \verb"N_1" rows correspond to the \verb"N_1" atoms in the first force configuration; the next \verb"N_2" rows correspond to the \verb"N_2" atoms in the second force configuration; and so on. Remember that the number of force configurations \verb"Nc_force" is specified in \verb"train.in".

\subsection{The energy.out file}

There are 2 columns. The first column gives the energies (in units of eV) calculated from the best solution. The second column gives the corresponding energies (in units of eV) from \verb"train.in". Each row corresponds to one energy/virial configuration in \verb"train.in". Remember that the number of energy/virial configurations is \verb"Nc - Nc_force", which should be the number of rows in \verb"energy.out".

\subsection{The virial.out file}

There are 2 columns. The first column gives the virials (in units of eV) calculated from the best solution. The second column gives the corresponding virials (in units of eV) from \verb"train.in". The number of rows is \verb"(Nc - Nc_force) x 6". The first 1/6 corresponds to the $xx$ component of the viral in the same order as the energy data in \verb"energy.out", followed by the $yy$, $zz$, $xy$, $yz$, and $zx$ components.

\bibliographystyle{plainnat}

\bibliography{refs}

\end{document}
